home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / SplitList.man < prev    next >
Encoding:
Text File  |  1992-06-03  |  10.4 KB  |  265 lines
  1.  
  2.  
  3.  
  4. Tcl_SplitList         C Library Procedures          Tcl_SplitList
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Tcl_SplitList,          Tcl_Merge,          Tcl_ScanElement,
  12.      Tcl_ConvertElement - manipulate Tcl lists
  13.  
  14. SSYYNNOOPPSSIISS
  15.      ##iinncclluuddee <<ttccll..hh>>
  16.  
  17.      int
  18.      TTccll__SSpplliittLLiisstt(_i_n_t_e_r_p, _l_i_s_t, _a_r_g_c_P_t_r, _a_r_g_v_P_t_r)
  19.  
  20.      char *
  21.      TTccll__MMeerrggee(_a_r_g_c, _a_r_g_v)
  22.  
  23.      int                                                           |
  24.      TTccll__SSccaannEElleemmeenntt(_s_r_c, _f_l_a_g_s_P_t_r)                                |
  25.  
  26.      int                                                           |
  27.      TTccll__CCoonnvveerrttEElleemmeenntt(_s_r_c, _d_s_t, _f_l_a_g_s)                           |
  28.  
  29. AARRGGUUMMEENNTTSS
  30.      Tcl_Interp   *_i_n_t_e_r_p      (out)     Interpreter to  use  for
  31.                                          error reporting.
  32.  
  33.      char         *_l_i_s_t        (in)      Pointer to a string with
  34.                                          proper list structure.
  35.  
  36.      int          *_a_r_g_c_P_t_r     (out)     Filled in with number of
  37.                                          elements in _l_i_s_t.
  38.  
  39.      char         ***_a_r_g_v_P_t_r   (out)     *_a_r_g_v_P_t_r will be  filled
  40.                                          in  with  the address of
  41.                                          an array of pointers  to
  42.                                          the strings that are the
  43.                                          extracted  elements   of
  44.                                          _l_i_s_t.    There  will  be
  45.                                          *_a_r_g_c_P_t_r  valid  entries
  46.                                          in  the  array, followed
  47.                                          by a NULL entry.
  48.  
  49.      int          _a_r_g_c         (in)      Number  of  elements  in
  50.                                          _a_r_g_v.
  51.  
  52.      char         **_a_r_g_v       (in)      Array  of   strings   to
  53.                                          merge  together  into  a
  54.                                          single    list.     Each
  55.                                          string   will  become  a
  56.                                          separate element of  the
  57.                                          list.
  58.  
  59.      char         *_s_r_c         (in)      String that is to become  |
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SplitList         C Library Procedures          Tcl_SplitList
  71.  
  72.  
  73.  
  74.                                          an element of a list.     |
  75.  
  76.      int          *_f_l_a_g_s_P_t_r    (in)                                     ||
  77.                                          Pointer  to word to fill  |
  78.                                          in   with    information  |
  79.                                          about _s_r_c.  The value of  |
  80.                                          *_f_l_a_g_s_P_t_r must be passed  |
  81.                                          to TTccll__CCoonnvveerrttEElleemmeenntt.    |
  82.  
  83.      char         *_d_s_t         (in)                                     ||
  84.                                          Place  to copy converted  |
  85.                                          list element.  Must con-  |
  86.                                          tain  enough  characters  |
  87.                                          to    hold     converted  |
  88.                                          string.                   |
  89.  
  90.      int          _f_l_a_g_s        (in)                                     ||
  91.                                          Information  about  _s_r_c.  |
  92.                                          Must be  value  returned  |
  93.                                          by   previous   call  to  |
  94.                                          TTccll__SSccaannEElleemmeenntt,  possi-  |
  95.                                          bly      OR-ed      with  |
  96.                                          TTCCLL__DDOONNTT__UUSSEE__BBRRAACCEESS.
  97. _________________________________________________________________
  98.  
  99.  
  100. DDEESSCCRRIIPPTTIIOONN
  101.      These procedures may be used to disassemble  and  reassemble
  102.      Tcl  lists.  TTccll__SSpplliittLLiisstt breaks a list up into its consti-
  103.      tuent elements, returning an array of pointers to  the  ele-
  104.      ments using _a_r_g_c_P_t_r and _a_r_g_v_P_t_r.  While extracting the argu-
  105.      ments, TTccll__SSpplliittLLiisstt obeys the  usual  rules  for  backslash
  106.      substitutions  and braces.  The area of memory pointed to by
  107.      *_a_r_g_v_P_t_r is dynamically allocated;  in addition to the array
  108.      of  pointers, it also holds copies of all the list elements.
  109.      It is the caller's responsibility to free  up  all  of  this
  110.      storage by calling
  111.  
  112.           ffrreeee((char *) *_a_r_g_v_P_t_r)
  113.      when the list elements are no longer needed.
  114.  
  115.      TTccll__SSpplliittLLiisstt normally returns TTCCLL__OOKK, which means the  list
  116.      was  successfully  parsed.   If  there was a syntax error in
  117.      _l_i_s_t, then TTCCLL__EERRRROORR is  returned  and  _i_n_t_e_r_p->_r_e_s_u_l_t  will
  118.      point  to  an  error  message  describing  the  problem.  If
  119.      TTCCLL__EERRRROORR is  returned  then  no  memory  is  allocated  and
  120.      *_a_r_g_v_P_t_r is not modified.
  121.  
  122.      TTccll__MMeerrggee is the inverse of TTccll__SSpplliittLLiisstt:  it takes a  col-
  123.      lection  of  strings  given by _a_r_g_c and _a_r_g_v and generates a
  124.      result string that has proper list  structure.   This  means
  125.      that commands like iinnddeexx may be used to extract the original
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SplitList         C Library Procedures          Tcl_SplitList
  137.  
  138.  
  139.  
  140.      elements again.  In addition, if the result of TTccll__MMeerrggee  is
  141.      passed  to TTccll__EEvvaall, it will be parsed into _a_r_g_c words whose
  142.      values will be the  same  as  the  _a_r_g_v  strings  passed  to
  143.      TTccll__MMeerrggee.   TTccll__MMeerrggee  will  modify  the list elements with
  144.      braces and/or backslashes in order  to  produce  proper  Tcl
  145.      list  structure.  The result string is dynamically allocated
  146.      using mmaalllloocc(());  the  caller  must  eventually  release  the
  147.      space using ffrreeee(()).
  148.  
  149.      If the result of TTccll__MMeerrggee is passed to  TTccll__SSpplliittLLiisstt,  the
  150.      elements  returned  by  TTccll__SSpplliittLLiisstt  will  be identical to
  151.      those passed into TTccll__MMeerrggee.  However, the converse  is  not
  152.      true:   if  TTccll__SSpplliittLLiisstt  is passed a given string, and the
  153.      resulting _a_r_g_c and _a_r_g_v are passed to TTccll__MMeerrggee, the result-
  154.      ing string may not be the same as the original string passed
  155.      to  TTccll__SSpplliittLLiisstt.   This  is  because  TTccll__MMeerrggee  may   use
  156.      backslashes and braces differently than the original string.
  157.  
  158.      TTccll__SSccaannEElleemmeenntt and TTccll__CCoonnvveerrttEElleemmeenntt  are  the  procedures  |
  159.      that  do all of the real work of TTccll__MMeerrggee.  TTccll__SSccaannEElleemmeenntt  |
  160.      scans its _s_r_c argument and determines how to use backslashes  |
  161.      and braces when converting it to a list element.  It returns  |
  162.      an overestimate of the  number  of  characters  required  to  |
  163.      represent  _s_r_c  as a list element, and it stores information  |
  164.      in *_f_l_a_g_s_P_t_r that is needed by TTccll__CCoonnvveerrttEElleemmeenntt.            |
  165.  
  166.      TTccll__CCoonnvveerrttEElleemmeenntt   is    a    companion    procedure    to  |
  167.      TTccll__SSccaannEElleemmeenntt.   It  does  the actual work of converting a  |
  168.      string to a list element.  Its _f_l_a_g_s argument  must  be  the  |
  169.      same    as    the   value   returned   by   TTccll__SSccaannEElleemmeenntt.  |
  170.      TTccll__CCoonnvveerrttEElleemmeenntt writes a proper list  element  to  memory  |
  171.      starting  at *_d_s_t and returns a count of the total number of  |
  172.      characters written, which will be no more  than  the  result  |
  173.      returned  by TTccll__SSccaannEElleemmeenntt.  TTccll__CCoonnvveerrttEElleemmeenntt writes out  |
  174.      only the actual list element without any leading or trailing  |
  175.      spaces:  it  is  up  to the caller to include spaces between  |
  176.      adjacent list elements.                                       |
  177.  
  178.      TTccll__CCoonnvveerrttEElleemmeenntt uses one of two different  approaches  to  |
  179.      handle the special characters in _s_r_c.  Wherever possible, it  |
  180.      handles special characters by surrounding  the  string  with  |
  181.      braces.   This  produces  clean-looking output, but can't be  |
  182.      used in some situations, such as when _s_r_c contains unmatched  |
  183.      braces.   In  these  situations,  TTccll__CCoonnvveerrttEElleemmeenntt handles  |
  184.      special characters by  generating  backslash  sequences  for  |
  185.      them.   The  caller may insist on the second approach by OR-  |
  186.      ing  the  flag  value  returned  by   TTccll__SSccaannEElleemmeenntt   with  |
  187.      TTCCLL__DDOONNTT__UUSSEE__BBRRAACCEESS.   Although  this will produce an uglier  |
  188.      result, it is useful in some  special  situations,  such  as  |
  189.      when  TTccll__CCoonnvveerrttEElleemmeenntt is being used to generate a portion  |
  190.      of an argument for a Tcl command.  In this case, surrounding  |
  191.      _s_r_c  with  curly  braces  would  cause the command not to be  |
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tcl_SplitList         C Library Procedures          Tcl_SplitList
  203.  
  204.  
  205.  
  206.      parsed correctly.
  207.  
  208.  
  209. KKEEYYWWOORRDDSS
  210.      backslash, convert, element, list, merge, split, strings
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Sprite v1.0                                                     4
  262.  
  263.  
  264.  
  265.